3.1 Topic Interface

The topic interface is accessed principally via the command woman. The same command can be accessed via the menu item ‘Help->Manuals->Read Man Page (WoMan)...’ once WoMan has been loaded. The command reads a manual topic in the minibuffer, which can be the basename of a man file anywhere in the man file structure. The “basename” in this context means the filename without any directory component and without any extension or suffix components that relate to the file type. So, for example, if there is a compressed source file in Chapter 5 of the UNIX Programmer’s Manual with the full pathname /usr/local/man/man5/man.conf.5.gz then the topic is man.conf. Provided WoMan is configured correctly, this topic will appear among the completions offered by woman. If more than one file has the same topic name then WoMan will prompt for which file to format. Completion of topics is case insensitive.

Clearly, woman has to know where to look for man files and there are two customizable user options that store this information: woman-manpath and woman-path. See Interface Options. If woman-manpath is not set explicitly then WoMan tries to pick up the information that would be used by the man command, as follows. If the environment variable MANPATH is set, which seems to be the standard mechanism under UNIX, then WoMan parses that. Otherwise, if WoMan can find a configuration file named (by default) man.conf (or something very similar), which seems to be the standard mechanism under GNU/Linux, then it parses that. To be precise, “something very similar” means starting with ‘man’ and ending with ‘.conf’ and possibly more lowercase letters, e.g., manual.configuration. The search path and/or precise full path name for this file are set by the value of the customizable user option woman-man.conf-path. If all else fails, WoMan uses a plausible default man search path.

If the above default configuration does not work correctly for any reason then simply customize the value of woman-manpath. To access man files that are not in a conventional man file hierarchy, customize the value of woman-path to include the directories containing the files. In this way, woman can access manual files anywhere in the entire file system.

There are two differences between woman-manpath and woman-path. Firstly, the elements of woman-manpath must be directories that contain directories of man files, whereas the elements of woman-path must be directories that contain man files directly. Secondly, the last directory component of each element of woman-path is treated as a regular (Emacs) match expression rather than a fixed name, which allows collections of related directories to be specified succinctly. Also, elements of woman-manpath can be conses, indicating a mapping from ‘PATH’ environment variable components to man directory hierarchies.

For topic completion to work, WoMan must build a list of all the manual files that it can access, which can be very slow, especially if a network is involved. For this reason, it caches various amounts of information, after which retrieving it from the cache is very fast. If the cache ever gets out of synchronism with reality, running the woman command with a prefix argument (e.g., C-u M-x woman) will force it to rebuild its cache. This is necessary only if the names or locations of any man files change; it is not necessary if only their contents change. It would always be necessary if such a change occurred whilst Emacs were running and after WoMan has been loaded. It may be necessary if such a change occurs between Emacs sessions and persistent caching is used, although WoMan can detect some changes that invalidate its cache and rebuild it automatically.

Customize the variable woman-cache-filename to save the cache between Emacs sessions. This is recommended only if the woman command is too slow the first time it is run in an Emacs session, while it builds its cache in main memory, which may be very slow. See The WoMan Topic Cache, for further details.